namespace cpp2 facebook.fboss.platform.showtech_config

//            +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+
//            |S|h|o|w|t|e|c|h| |C|o|n|f|i|g|
//            +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+
//
// ShowtechConfig defines all the hardware components and devices that the
// showtech utility will collect diagnostic information from during
// troubleshooting and debugging operations. This includes I2C devices, GPIOs,
// PSUs, PEMs, fan controllers, and power status monitoring.
//
// The showtech utility uses this configuration to systematically collect
// hardware state and diagnostic data from various platform components,
// generating a comprehensive snapshot for debugging hardware and firmware
// issues.
//
// All paths should be based on /run/devmap generated by Platform Manager.

// ============================================================================

// Main configuration structure for the showtech utility.
//
// `i2cBusIgnore`: Set of I2C bus numbers to skip during data collection.
// These buses might be unstable or not relevant for diagnostics.
//
// `psus`: List of Power Supply Unit (PSU) identifiers to collect data from.
// These are the paths generated by Platform Manager in /run/devmap.
//
// `gpios`: List of GPIO configurations for reading digital signals and
// status lines. See Gpio struct below.
//
// `pems`: List of Power Entry Module (PEM) configurations for power
// monitoring. See Pem struct below.
//
// `fanspinners`: List of fan spinner devices for collecting fan speed and
// status information. See FanSpinnerDevice struct below.
//
// `i2cDumpDevices`: List of I2C device addresses to dump register data from.
// These are the devices paths generated by Platform Manager in /run/devmap.
//
// `scPowerGood`: Optional configuration for switch card power good status
// monitoring. See SwitchCardPowerGoodStatus struct below.
struct ShowtechConfig {
  1: set<string> i2cBusIgnore;
  2: list<string> psus;
  3: list<Gpio> gpios;
  4: list<Pem> pems;
  5: list<FanSpinnerDevice> fanspinners;
  6: list<string> i2cDumpDevices;
  7: optional SwitchCardPowerGoodStatus scPowerGood;
}

// GPIO (General Purpose Input/Output) configuration.
//
// `path`: Path to the GPIO chip device (e.g., "/dev/gpiochip0").
// These are the paths generated by Platform Manager in /run/devmap.
//
// `lines`: List of specific GPIO lines to read from this chip. See
// GpioLine struct below.
struct Gpio {
  1: string path;
  2: list<GpioLine> lines;
}

// Individual GPIO line configuration.
//
// `name`: Human-readable name for this GPIO line (e.g., "POWER_BUTTON",
// "RESET_SIGNAL"). This name will be used in the showtech output for
// clarity.
//
// `lineIndex`: Zero-based index of the line on the GPIO chip. This
// corresponds to the hardware pin number on the GPIO controller.
struct GpioLine {
  1: string name;
  2: i32 lineIndex;
}

// Power Entry Module (PEM) configuration.
//
// `name`: Name identifier for this PEM (e.g., "PEM1", "PEM2"). This name
// will be used in the showtech output.
//
// `presenceSysfsPath`: Sysfs path to read PEM presence status
// Use paths generated by Platform Manager in /run/devmap.
//
// `inputOkSysfsPath`: Sysfs path to read input power OK status
// Use paths generated by Platform Manager in /run/devmap.
//
// `statusSysfsPath`: Sysfs path to read overall PEM status
// Use paths generated by Platform Manager in /run/devmap.
struct Pem {
  1: string name;
  2: string presenceSysfsPath;
  3: string inputOkSysfsPath;
  4: string statusSysfsPath;
}

// Fan spinner device configuration.
//
// `path`: Base sysfs path to the fan controller device
// Use paths generated by Platform Manager in /run/devmap.
//
// `sysfsAttributes`: List of sysfs attributes to read from this device.
// These typically include fan speeds (RPM), PWM values, and fault status.
// See SysfsAttribute struct below.
struct FanSpinnerDevice {
  1: string path;
  2: list<SysfsAttribute> sysfsAttributes;
}

// Switch card power good status configuration.
//
// `sysfsAttribute`: Power good status via a sysfs attribute. Use this when
// the power good signal is exposed as a sysfs file. See SysfsAttribute
// struct below.
//
// `gpioAttribute`: Power good status via a GPIO signal. Use this when the
// power good signal is connected to a GPIO pin. See Gpio struct above.
//
// Note: Only one of sysfsAttribute or gpioAttribute should be set,
// depending on how the power good signal is exposed in the hardware.
struct SwitchCardPowerGoodStatus {
  1: optional SysfsAttribute sysfsAttribute;
  2: optional Gpio gpioAttribute;
}

// Sysfs attribute definition.
//
// `name`: Human-readable name for this attribute (e.g., "fan1_input",
// "pwm1"). This name will be used in the showtech output.
//
// `path`: Full sysfs path to the attribute file
// Use paths generated by Platform Manager in /run/devmap.
struct SysfsAttribute {
  1: string name;
  2: string path;
}
